Skip to main content

7장. 로컬 추론 서버 설정하기

7.1 LM Studio 서버 모드 이해하기​

LM Studio의 서버 모드는 로컬 모델을 다른 프로그램에서 호출할 수 있게 해 줍니다. 채팅 UI는 사람이 직접 대화하는 화면이고, 서버 모드는 IDE, 스크립트, 에이전트가 모델을 사용할 수 있게 하는 통로입니다.

서버를 켜면 LM Studio는 로컬 주소에서 API 요청을 받습니다. Continue 같은 IDE 확장은 이 주소로 메시지를 보냅니다. 서버가 꺼져 있으면 IDE는 모델에 접근할 수 없습니다. 모델이 로드되어 있지 않거나 모델 ID가 틀려도 요청이 실패할 수 있습니다.

로컬 서버를 이해할 때 가장 중요한 단어는 endpoint입니다. endpoint는 API 요청을 보내는 주소입니다. OpenAI 호환 API의 경우 채팅 요청은 /v1/chat/completions 같은 경로로 보내집니다. LM Studio의 OpenAI 호환 문서는 기본 예시에서 서버 포트 1234를 가정하고 http://localhost:1234/v1을 base URL로 사용합니다.

[이미지 7-1] LM Studio 서버 모드 화면.

7.2 localhost, 포트, API endpoint 개념​

localhost는 내 컴퓨터 자신을 가리키는 이름입니다. 브라우저에서 http://localhost:1234를 입력하면 외부 인터넷이 아니라 내 컴퓨터의 1234번 포트로 접속을 시도합니다. 포트는 한 컴퓨터 안에서 여러 서버 프로그램을 구분하는 번호입니다. 웹 개발자가 3000번 포트에서 프론트엔드 개발 서버를 띄우고, 8000번 포트에서 백엔드 서버를 띄우는 것과 같은 개념입니다.

LM Studio 서버가 1234번 포트에서 실행되면, Continue는 http://localhost:1234/v1로 요청해야 합니다. 만약 LM Studio에서 포트를 4321로 바꾸었다면 Continue 설정도 http://localhost:4321/v1로 바꿔야 합니다. 서버 포트와 IDE 설정이 다르면 연결되지 않습니다.

API endpoint는 더 구체적인 요청 경로입니다. base URL이 건물 주소라면 endpoint는 방 번호에 가깝습니다. 채팅, 임베딩, 모델 목록 조회 등 기능마다 endpoint가 다를 수 있습니다. Continue 같은 도구는 내부적으로 필요한 endpoint를 호출하므로 사용자가 매번 외울 필요는 없습니다. 그러나 문제가 생겼을 때 base URL이 맞는지 확인하는 능력은 필요합니다.

7.3 OpenAI-compatible API란 무엇인가​

OpenAI-compatible API는 기존 OpenAI API와 비슷한 형식으로 요청과 응답을 주고받는 인터페이스를 말합니다. 이 구조의 장점은 큽니다. 이미 OpenAI API를 지원하는 도구라면 base URL만 바꿔 로컬 서버를 호출할 수 있습니다. LM Studio 공식 문서도 Python, JavaScript 등 OpenAI 클라이언트의 base URL을 LM Studio 서버로 바꾸는 예시를 제공합니다.

예를 들어 원래 클라우드 OpenAI 서버로 보내던 요청이 있었다면, base URL을 http://localhost:1234/v1로 바꾸고 모델 이름을 LM Studio에서 로드한 모델 ID로 맞추는 식입니다. API 키는 로컬 서버에서는 실제 인증에 쓰이지 않더라도, 클라이언트 라이브러리가 요구할 수 있어 임의 값이 필요할 수 있습니다.

이 호환성 덕분에 로컬 모델 생태계가 빠르게 확장됩니다. IDE 확장, 스크립트, 테스트 도구, 에이전트가 모두 같은 방식으로 모델을 호출할 수 있습니다. 다만 “호환”은 “완전히 동일”을 뜻하지 않습니다. 모든 endpoint나 모든 파라미터가 똑같이 동작한다고 가정하면 안 됩니다. 문제가 생기면 해당 도구와 LM Studio 문서를 함께 확인해야 합니다.

[코드 예제 7-1] OpenAI 클라이언트 base URL을 로컬 LM Studio로 바꾸는 Python 예시.

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:1234/v1",
    api_key="lm-studio"
)

response = client.chat.completions.create(
    model="LM_STUDIO_MODEL_ID",
    messages=[{"role": "user", "content": "Say hello in Korean."}],
    temperature=0.2,
)

print(response.choices[0].message.content)

7.4 모델 ID를 정확히 맞춰야 하는 이유​

로컬 서버 연결에서 자주 생기는 오류가 모델 ID 불일치입니다. IDE 설정에는 model 값을 넣어야 합니다. 이 값은 사용자가 마음대로 붙이는 별칭이 아니라, 서버가 인식하는 모델 식별자여야 합니다. LM Studio에서 로드한 모델 ID와 Continue 설정의 모델 값이 다르면 요청이 실패하거나, 다른 모델을 호출할 수 있습니다.

초보자는 모델의 표시 이름과 파일 이름, ID를 혼동하기 쉽습니다. 어떤 UI에서는 예쁘게 정리된 이름을 보여 주고, API에서는 다른 식별자를 요구할 수 있습니다. 따라서 설정할 때는 LM Studio의 서버 또는 모델 정보 화면에서 실제 API 모델 ID를 확인하는 것이 좋습니다.

모델 ID 문제를 줄이는 방법은 이름을 단순하게 관리하는 것입니다. 가능하면 Continue의 name은 사람이 알아보기 쉬운 이름으로 두고, model은 LM Studio가 요구하는 정확한 ID를 넣습니다. 예를 들어 name은 “Local Coder 7B Chat”처럼 쓰고, model은 LM Studio에 표시된 실제 모델 ID를 그대로 복사합니다.

7.5 서버가 켜졌는지 확인하는 방법​

서버가 켜졌는지 확인하는 가장 쉬운 방법은 LM Studio 화면에서 상태를 보는 것입니다. Developer 또는 Local Server 관련 화면에서 서버가 Running 상태인지 확인합니다. 포트 번호도 확인합니다. 그다음 브라우저나 터미널에서 간단한 요청을 보내 볼 수 있습니다.

터미널에서 확인하려면 curl을 사용할 수 있습니다. 운영체제와 LM Studio 버전에 따라 모델 목록 endpoint 응답이 다를 수 있으므로, 출간 전에는 최신 문서로 확인해야 합니다. 기본 개념은 서버 주소가 응답하는지 확인하는 것입니다.

curl http://localhost:1234/v1/models

정상이라면 로드되었거나 사용 가능한 모델 목록이 JSON 형태로 나올 수 있습니다. 연결이 거부되면 서버가 꺼져 있거나 포트가 다를 수 있습니다. 응답은 오지만 모델 호출이 실패하면 모델 ID나 요청 형식 문제일 수 있습니다.

[실습 화면 7-2] 터미널에서 curl http://localhost:1234/v1/models를 실행한 화면.

7.6 여러 모델을 바꿔가며 테스트하기​

LM Studio의 장점 중 하나는 여러 모델을 비교하기 쉽다는 점입니다. 같은 질문을 여러 모델에 던져 보고, 답변 품질과 속도를 비교할 수 있습니다. 다만 모델을 바꿀 때는 메모리 상태를 확인해야 합니다. 이전 모델이 여전히 메모리에 남아 있으면 새 모델 로딩에 실패하거나 시스템이 느려질 수 있습니다.

같은 프롬프트, 같은 temperature, 비슷한 context length로 비교합니다. 모델별로 한 번만 물어보고 결론을 내리지 말고, 최소 5개 작업으로 비교합니다. 코딩 모델은 문제 유형에 따라 강약이 다르기 때문입니다.

7.7 로컬 서버 장애 확인 체크리스트​

로컬 서버가 연결되지 않을 때는 다음 순서로 확인합니다.

  • 첫째, LM Studio 앱이 실행 중인지 봅니다.
  • 둘째, 서버가 Running 상태인지 봅니다.
  • 셋째, 포트 번호가 Continue 설정과 같은지 봅니다.
  • 넷째, 모델이 로드되어 있는지 봅니다.
  • 다섯째, 모델 ID가 정확한지 봅니다.
  • 여섯째, 방화벽이나 보안 프로그램이 로컬 연결을 막지 않는지 봅니다.

[표 7-1] 로컬 서버 문제 해결 체크리스트.